MacFormat 1995 January/macformat-020.iso/Shareware City/Developers/apps.to.go/DTS.Lib/DTS.Lib.headers/File2.h

C/C++ Source or Header | 1994-06-10 | 13.1 KB | 363 lines | [TEXT/KAHL]

#ifndef __FILE2__
#define __FILE2__

#ifndef __TYPES__
#include <Types.h>
#endif



OSErr            DefaultInitDocument(FileRecHndl frHndl, short version,
                                    short numUndos, short numSaveUndos);
    /*
    **    ¶ Do standard AppsToGo document initialization.
    **
    **    INPUT:    frHndl            Recently created (most likely by the framework) file
    **                            reference handle.
    **            version            Version number to store into the document.
    **            numUndos        The number of undos to be managed by the hierarchical
    **                            document architecture.
    **            numSaveUndos    The number of undos to be saved with the document
    **                            (commonly none, so 0).
    **    RESULT:    OSErr
    **
    **    This function does the standard document initialization.  The standard document
    **    uses the hierarchical document package TreeObj.  Read the TreeObj documentation for
    **    more information. */



OSErr            DisposeDocument(FileRecHndl frHndl);
    /*
    **    ¶ Dispose of an AppsToGo document.
    **
    **    INPUT:    frHndl        The file reference being disposed of.
    **    RESULT:    OSErr
    **
    **    This function is automatically called by such functions as DisposeOneWindow.  It
    **    calls the designated free document procedure, which by default is FreeDocument.
    **    The free document procedure is responsible for disposing of any and all handles
    **    that were created by the init document procedure. */



OSErr            NewDocument(FileRecHndl *returnHndl, OSType sftype, Boolean incTitleNum);
    /*
    **    ¶ Create new AppsToGo document.
    **
    **    INPUT:    sftype            The OSType of the desired document.
    **            incTitleNum        Pass in true if you want the document number which is
    **                            (optionally) appended to the title incremented.
    **    OUTPUT:    returnHndl        The frHndl created is returned here.
    **                            Note that there are two special cases that you can call
    **                            this function.  The purpose for both is to change
    **                            the untitledCount value.  If you pass in an sftype of 0,
    **                            then the frHndl value is used as an indicator as to what
    **                            to do with the untitledCount value.  If you pass in 0
    **                            for the frHndl value, untitledCount is reset to 0.
    **                            If you pass in a -1, untitledCount is decremented.
    **    RESULT:    OSErr            If an error is returned, then there is no returnHndl.
    **
    **    This function is called by the application, directly or indirectly.  Even if you
    **    have used the application editor to set up AppWannabe to automatically open
    **    document windows (file-based or not), this gets called.
    **
    **    NewDocument first calls the AppWannabe function InitDocumentSize to allow the
    **    application to declare how large the file reference handle should be.  It then
    **    creates the frHndl based on the return value of InitDocumentSize
    **    (via NewHandleClear), and then initializes the fields to their default values.
    **
    **    NewDocument then calls another AppWannabe function called InitDocument.  The
    **    purpose of this AppWannabe function is to change any of the defaults that aren’t
    **    appropriate for the document.
    **
    **    Note that the typical way to create document with AppsToGo (because it is the
    **    easiest) is to create them with the application editor.  NewDocument, for backwards
    **    compatibility notes if there is an AppsToGo application editor entry for this
    **    OSType.  If so, then there is a lot more information directly available for this
    **    document.  If the document being created was described with the editor, then read
    **    part 1 below.  If you are calling NewDocument directly without having described
    **    this OSType with the AppsToGo application editor, then read part 2 below.
    **    (The part 2 technique is really only for backwards compatibility.)
    **
    **    PART 1:    The document title is entered in the AppsToGo editor.  If there is no
    **            title entered there, or if the title starts with a space, then no default
    **            title is placed in the document reference.  (When a window is created, if
    **            there is no document name, then the 'WIND' resource title is used as-is
    **            instead.)
    **
    **            If true is passed in for incTitleNum, then if a valid title was entered in
    **            the AppsToGo editor, then untitledCount is incremented, and then appended
    **            to the title.
    **
    **    PART 2:    New documents will be created with a default title.  This title is created
    **            by appending a number to the corresponding STR# individual string.  The
    **            STR# resource ID #259 holds the default text for the window titles.  Which
    **            string number is determined by the OSType array gTypeList.  gTypeList
    **            contains all of the file types that can be opened by the application.  The
    **            list is walked, and the location in the gTypeList array that holds the
    **            correct file type is used as an index into the STR# resource.  If the file
    **            type isn’t found in the list, then the first string in the STR# resource
    **            is used.
    **
    **            The next greatest integer is appended to the end of the individual string
    **            selected for the document.  If incTitleNum is true, then the global
    **            integer is first incremented prior to appending the number.
    **
    **            If you want to create a document with the title found in the 'WIND'
    **            resource, first call NewDocument.  After you have the frHndl for the
    **            document, set the file name in the (*frHndl)->fileState.fss.name field to
    **            an empty string.  When the window is opened for this document, if this
    **            name is an empty string, it titles the window according to what is found
    **            in the 'WIND' resource for that window.  If this field is not an empty
    **            string, then the 'WIND' title is overridden, and the file name is used. */



OSErr            OpenDocument(FileRecHndl *result, FSSpecPtr fileToOpen, char permission);
    /*
    **    ¶ Open an AppsToGo document.
    **
    **    INPUT:    fileToOpen        A pointer to the FSSpec for the file to open, or nil if
    **                            the user should determine via StandardFile.
    **                            Also, if you want to open a movie, pass in kOpenMovie for
    **                            the FSSpec pointer.
    **            permission        As you would expect -- fsRdPerm or fsRdWrPerm.
    **    RESULT:    OSErr
    **
    **    This function does the human-interface thing for opening a document.  It
    **    also calls NewDocument to initialize a document.  To actually read in
    **    the data, OpenDocument calls the designated read document procedure, which by
    **    default is ReadDocument.  The read document procedure is responsible for reading
    **    the document data into ram in association with the FileRecHndl created by
    **    NewDocument. */



OSErr            SaveDocument(FileRecHndl frHndl, WindowPtr window, short saveMode);
    /*
    **    ¶ Save an AppsToGo document.
    **
    **    INPUT:    frHndl
    **            window
    **            saveMode    The mode for saving -- kSave, kSaveAs, kClose, kQuit
    **    RESULT:    OSErr
    **
    **    This function does the human-interface thing for saving a document.  The
    **    human-interface presented to the user is determined by the saveMode.
    **
    **    To actually write out the data, SaveDocument calls the designated write document
    **    procedure, which by default is WriteDocument.  The write document procedure is
    **    responsible for writing the document data to the designated file. */



void            ConvertOldToNewSFReply(SFReply *oldReply, StandardFileReply *newReply);
    /*
    **    ¶ Convert pre-system-7 standard file record to a system-7 record.
    **
    **    INPUT:    oldReply
    **    OUTPUT:    newReply
    **
    **    When running on a pre-7.0 system, SFGetFile or SFPutFile is called.  Then
    **    ConvertOldToNewSFReply is called to convert the reply record to the new
    **    format.  This allows the rest of the application to use only a single
    **    record format. */



Boolean            DisplayGetFile(StandardFileReply *reply, short typeListLen,
                               SFTypeList typeList);
    /*
    **    ¶ Do a system-independent (system 6 or 7+) Standard Get File.
    **
    **    INPUT:    typeListLen        Length of typeList.
    **            typeList        List of acceptable OSTypes to be displayed by
    **                            StandardFile.
    **    OUTPUT:    reply            Reply record -- result of StandardFile.
    **    RESULT:    Boolean            Returns true if reply is good.
    **
    **    Simple routine to display a list of files with our file type, independent of
    **    system (6 or 7). */



Boolean            DisplayPutFile(StandardFileReply *reply);
    /*
    **    ¶ Do a system-independent (system 6 or 7+) Standard Put File.
    **
    **    IN/OUT:    reply            Reply record for standard file.
    **    RESULT:    Boolean            Returns true if reply is good.
    **
    **    Displays the StandardFile PutFile dialog box. Fills out the passed reply
    **    record, and returns the sfGood field as a result. */



OSErr            UseDocResFile(FileRecHndl frHndl, short *oldRes, char perm);
    /*
    **    ¶ Use (and possibly create) resource fork of designated file.
    **
    **    INPUT:    frHndl
    **            perm
    **    OUTPUT:    oldRes
    **    RESULT:    OSErr
    **
    **    Use the resource fork for the designated document file.  This function
    **    also returns the old CurResFile, so you can set it back when you are done.
    **    Simply call this function, whether or not you have a resource fork.  If
    **    there isn’t a resource fork, then one will be created.  If there is one,
    **    but it isn’t open yet, it will be opened.  If it is already opened, it
    **    sets it as the current resource fork.  What more do you want? */



OSErr            CloseDocResFile(FileRecHndl frHndl);
    /*
    **    ¶ Close document res file.
    **
    **    INPUT:    frHndl
    **    RESULT:    OSErr
    **
    **    If there is a resource fork opened for this document (via UseDocResFile),
    **    this closes it. */



long            GetModNum(void);
    /*
    **    ¶ Get modification number of document.
    **
    **    Get the modification number for the document.  TreeObj automatically
    **    increments this. */



Boolean            GetDocDirty(FileRecHndl frHndl);
    /*
    **    ¶ Find out if the document is dirty.
    **
    **    INPUT:    frHndl
    **
    **    Get the dirty state of the document. */



Boolean            GetWindowDirty(WindowPtr window);
    /*
    **    ¶ Find out if a window’s document is dirty.
    **
    **    INPUT:    window
    **
    **    Given a window, return the dirty state of the associated document. */



void            SetDocDirty(FileRecHndl frHndl);
    /*
    **    ¶ Set the document dirty.
    **
    **    INPUT:    frHndl
    **
    **    Set the document dirty. */



void            SetWindowDirty(WindowPtr window);
    /*
    **    ¶ Set the window’s document dirty.
    **
    **    INPUT:    window
    **
    **    Given a window, set the associated document as dirty. */



OSErr            SetDefault(short newVRefNum,  long newDirID,
                           short *oldVRefNum, long *oldDirID);
    /*
    **    ¶ Set default volume and directory.
    **
    **    INPUT:    newVRefNum
    **            newDirID
    **    OUTPUT:    oldVRefNum
    **            oldDirID
    **    RESULT:    OSErr
    **
    **    The SetDefault function sets the default volume and directory to the volume
    **    specified by newVRefNum and the directory specified by newDirID. The current
    **    default volume and directory are returned in oldVRefNum and oldDir and should be
    **    used to restore things to their previous condition *as soon as possible* with the
    **    RestoreDefault function. These two functions are designed to be used as a wrapper
    **    around Standard C I/O routines where the location of the file is implied to be the
    **    default volume and directory. In other words, this is how you should use these
    **    functions:
    **
    **        err = SetDefault(newVRefNum, newDirID, &oldVRefNum, &oldDirID);
    **        if (!err)
    **            {
    **                -- call the Stdio functions like remove, rename, tmpfile, fopen,   --
    **                -- freopen, etc. or non-ANSI extentions like fdopen, fsetfileinfo, --
    **                -- create, open, unlink, etc. here!                                   --
    **
    **                err = RestoreDefault(oldVRefNum, oldDirID);
    **            }
    **
    **    By using these functions as a wrapper, you won’t need to open a working directory
    **    (because they use HSetVol) and you won’t have to worry about the effects of using
    **    HSetVol (documented in Technical Note #140: Why PBHSetVol is Dangerous
    **    and in the Inside Macintosh: Files book in the description of the HSetVol and
    **    PBHSetVol functions) because the default volume/directory is restored before
    **    giving up control to code that might be affected by HSetVol.
    **    Use this and the below call instead of the old-style FSpSetWD and FSpResetWD. */



OSErr            RestoreDefault(short oldVRefNum, long oldDirID);
    /*
    **    ¶ Restore default volume and directory.
    **
    **    INPUT:    oldVRefNum
    **            oldDirID
    **    RESULT:    OSErr
    **
    **    Resets the default directory to what it was prior to calling SetDefault. */



OSErr            GetFileLocation(short refNum, short *vRefNum, long *dirID,
                                StringPtr fileName);
    /*
    **    ¶ Get vRefNum, dirID, and fileName of a file.
    **
    **    INPUT:    refNum
    **    OUTPUT:    vRefNum
    **            dirID
    **            fileName
    **    RESULT:    OSErr
    **
    **    Get the vRefNum, dirID, and fileName of a file.
    **    (vRefNum and dirID are its location). */



OSErr            CurResOnly(Handle *hndl);
    /*
    **    ¶ Find out if resource belongs to current res file.
    **
    **    IN/OUT:    hndl
    **    RESULT:    OSErr
    **
    **    After getting a resource, you can’t actually be sure that it came from the current
    **    resource file.  Even if you make a call such as Get1Resource, starting with
    **    system 7.1, you can’t really be sure that it came from the current resource file.
    **    (The resource files may be overridden, or they may be flagged to be extended, as is
    **    the case with font files.)  This checks to see that the resource actually came from
    **    the current resource file.  If it didn’t, then the handle returned is nil, and the
    **    error returned is resNotFound.  (You probably don’t need this function unless you
    **    are doing some kind of resource-editing function.) */



#endif